---
title: 快速开始
description: Create your first AI Agent from scratch
---

import { Steps } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
import quickstartExample from '../../../../../../examples/docs/quickstart/index.ts?raw';

## 项目设置

<Steps>

1. 创建项目并初始化 npm。此操作只需执行一次。

   ```bash
   mkdir my_project
   cd my_project
   npm init -y
   ```

2. 安装 Agents SDK。

   ```bash
   npm install @openai/agents zod@3
   ```

3. 设置 OpenAI API 密钥。若尚未拥有，请按照[这些说明](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)创建 OpenAI API 密钥。

   ```bash
   export OPENAI_API_KEY=sk-...
   ```

   或者，您可以调用 `setDefaultOpenAIKey('<api key>')` 以编程方式设置密钥，并使用 `setTracingExportApiKey('<api key>')` 进行追踪。
   详见[SDK 配置](/openai-agents-js/zh/guides/config)。

</Steps>

## 创建第一个智能体

智能体通过 instructions 和名称进行定义。

```typescript
import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});
```

## 运行第一个智能体

您可以使用 `run` 方法来运行智能体。通过传入要启动的智能体和要传递的输入来触发一次运行。

这将返回包含最终输出以及该次运行期间执行的任何操作的运行结果。

```typescript
import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const result = await run(agent, 'When did sharks first appear?');

console.log(result.finalOutput);
```

## 为智能体提供工具

您可以为智能体提供工具，用于查询信息或执行操作。

```typescript
import { Agent, tool } from '@openai/agents';

const historyFunFact = tool({
  // The name of the tool will be used by the agent to tell what tool to use.
  name: 'history_fun_fact',
  // The description is used to describe **when** to use the tool by telling it **what** it does.
  description: 'Give a fun fact about a historical event',
  // This tool takes no parameters, so we provide an empty Zod Object.
  parameters: z.object({}),
  execute: async () => {
    // The output will be returned back to the Agent to use
    return 'Sharks are older than trees.';
  },
});

const agent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
  // Adding the tool to the agent
  tools: [historyFunFact],
});
```

## 添加更多智能体

可以以类似方式定义更多智能体，将问题拆解为更小的部分，使智能体更专注于当前任务。这也允许您为不同问题在智能体上定义不同的模型。

```typescript
const historyTutorAgent = new Agent({
  name: 'History Tutor',
  instructions:
    'You provide assistance with historical queries. Explain important events and context clearly.',
});

const mathTutorAgent = new Agent({
  name: 'Math Tutor',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});
```

## 定义交接

为了在多个智能体之间进行编排，您可以为智能体定义 `handoffs`。这将使智能体能够将对话传递给下一个智能体。这将在运行过程中自动发生。

```typescript
// Using the Agent.create method to ensures type safety for the final output
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});
```

运行结束后，您可以通过查看运行结果上的 `finalAgent` 属性来了解哪个智能体生成了最终响应。

## 运行智能体编排

Runner 负责处理各个智能体的执行、潜在的交接以及工具调用。

```typescript
import { run } from '@openai/agents';

async function main() {
  const result = await run(triageAgent, 'What is the capital of France?');
  console.log(result.finalOutput);
}

main().catch((err) => console.error(err));
```

## 整合到一起

让我们将以上内容整合为一个完整示例。将其放入 `index.js` 文件并运行。

<Code lang="typescript" code={quickstartExample} title="快速上手" />

## 查看追踪

Agents SDK 将自动为您生成追踪。这使您能够审查智能体的运行方式、调用了哪些工具，或交接给了哪个智能体。

要查看一次智能体运行期间发生的情况，请前往
[OpenAI Dashboard 中的 Trace 查看器](https://platform.openai.com/traces)。

## 后续步骤

了解如何构建更复杂的智能体流程：

- 了解如何配置[智能体](/openai-agents-js/zh/guides/agents)。
- 了解[运行智能体](/openai-agents-js/zh/guides/running-agents)。
- 了解[工具](/openai-agents-js/zh/guides/tools)、[护栏](/openai-agents-js/zh/guides/guardrails)和[模型](/openai-agents-js/zh/guides/models)。
